
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>Explaining the first job in detail &#8212; LAVA 2024.05 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="lavacli" href="lavacli.html" />
    <link rel="prev" title="Submitting your first job" href="first-job.html" />
    <link rel="canonical" href="https://docs.lavasoftware.org/lava/explain_first_job.html" />
  
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>


  </head><body>

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="index.html"><span><img src="_static/lava.png"></span>
          LAVA</a>
        <span class="navbar-text navbar-version pull-left"><b>2024.05</b></span>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            
                <li><a href="genindex.html">Index</a></li>
                <li><a href="contents.html">Contents</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="index.html">Site <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction to LAVA</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="contents.html">Contents</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary of terms</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="support.html">Getting support</a></li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Explaining the first job in detail</a><ul>
<li><a class="reference internal" href="#top-level-elements-of-a-test-job">Top level elements of a test job</a></li>
<li><a class="reference internal" href="#actions-within-the-test-job">Actions within the test job</a><ul>
<li><a class="reference internal" href="#deploy-action-for-qemu">Deploy action for QEMU</a><ul>
<li><a class="reference internal" href="#example-of-deploy-label-substitution">Example of deploy label substitution</a></li>
</ul>
</li>
<li><a class="reference internal" href="#boot-action-for-qemu">Boot action for QEMU</a></li>
<li><a class="reference internal" href="#test-action-for-qemu">Test action for QEMU</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</ul>
</li>
              
            
            
              
                
  <li>
    <a href="first-job.html" title="Previous Chapter: Submitting your first job"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">&laquo; Submitting yo...</span>
    </a>
  </li>
  <li>
    <a href="lavacli.html" title="Next Chapter: lavacli"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">lavacli &raquo;</span>
    </a>
  </li>
              
            
            
            
            
              <li class="hidden-sm"></li>
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
    <div class="body col-md-12 content" role="main">
      
  <section id="explaining-the-first-job-in-detail">
<span id="explain-first-job"></span><span id="index-0"></span><h1>Explaining the first job in detail<a class="headerlink" href="#explaining-the-first-job-in-detail" title="Permalink to this heading">¶</a></h1>
<p><a class="reference external" href="examples/test-jobs/qemu-pipeline-first-job.yaml">Download / view</a> the
complete first job YAML.</p>
<p>As the first job, this is a simple emulated test which does not need any extra
hardware, it does not use protocols and runs as a single job. The elements of
the first job are described in detail below.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This kind of test is generally termed <code class="docutils literal notranslate"><span class="pre">singlenode</span></code>.</p>
</div>
<section id="top-level-elements-of-a-test-job">
<h2>Top level elements of a test job<a class="headerlink" href="#top-level-elements-of-a-test-job" title="Permalink to this heading">¶</a></h2>
<ul>
<li><p><strong>comments</strong> - One of the reasons why V2 uses YAML for job
submission is because YAML supports comments. <strong>Please use comments
liberally</strong>. Comments are preserved in the job definition which can
be viewed and downloaded from the instance. Comments are not passed
to the dispatcher.</p></li>
<li><p><strong>device_type</strong> - a label which must match the type of <a class="reference internal" href="glossary.html#term-device"><span class="xref std std-term">device</span></a>
declared on the instance to which you want to submit this job. Each
<a class="reference internal" href="glossary.html#term-device-type"><span class="xref std std-term">device type</span></a> can have one or more devices available. In this case,
<code class="docutils literal notranslate"><span class="pre">qemu</span></code>.</p></li>
<li><p><strong>job_name</strong> - your own free text name for this job. This name is used in the
server side tables but has no further relevance for the dispatcher. There is
no need to make this into a single long word, any valid YAML string is
allowed, so commas, capitalization and whitespace are fine. Long job names,
in particular, need to include whitespace. Avoid the temptation to use a
build URL as the job name, use <a class="reference internal" href="standard-test-jobs.html#job-metadata"><span class="std std-ref">Metadata</span></a> instead.</p></li>
<li><p><strong>timeouts</strong> - a range of things can go wrong inside a LAVA test job, so the
test writer needs to indicate how long parts of the job should take. This
allows LAVA to fail jobs which have hung and return the device to scheduling
for the next test job. Timeouts at the top level include the job, the default
timeout per action and can include the default timeout for the device to
respond using a connection.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="timeouts.html#timeouts"><span class="std std-ref">Timeouts</span></a></p>
</div>
</li>
<li><p><strong>priority</strong> - supports any integers in [0, 100]. Three shortcuts are also
available: <code class="docutils literal notranslate"><span class="pre">high</span></code> (100), <code class="docutils literal notranslate"><span class="pre">medium</span></code> (50) and <code class="docutils literal notranslate"><span class="pre">low</span></code> (0). The
<a class="reference internal" href="glossary.html#term-scheduler"><span class="xref std std-term">scheduler</span></a> considers the job priority when ordering the queue to
consider which job should run next.</p></li>
<li><p><strong>visibility</strong> - supports values of <code class="docutils literal notranslate"><span class="pre">public</span></code>, <code class="docutils literal notranslate"><span class="pre">personal</span></code> and <code class="docutils literal notranslate"><span class="pre">group</span></code>
and controls who is allowed to view the job and the results generated by the
job. This includes whether the results are available to queries and to
charts.</p>
<p><code class="docutils literal notranslate"><span class="pre">group</span></code> visibility setting should list the groups users must be in to
be allowed to see the job. If more than one group is listed, users must
be in all the listed groups to be able to view the job or the results:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">visibility</span><span class="p">:</span>
  <span class="n">group</span><span class="p">:</span>
    <span class="o">-</span> <span class="n">developers</span>
    <span class="o">-</span> <span class="n">project</span>
</pre></div>
</div>
<p>In this example, users must be members of both <code class="docutils literal notranslate"><span class="pre">developers</span></code> group and
<code class="docutils literal notranslate"><span class="pre">project</span></code> group.</p>
</li>
<li><p><strong>context</strong> - Not all testjobs will use a <a class="reference internal" href="glossary.html#term-job-context"><span class="xref std std-term">job context</span></a>, it is
available to override some of the server-side device configuration templates.
In this case, <code class="docutils literal notranslate"><span class="pre">arch:</span> <span class="pre">amd64</span></code> sets the template to use the
<code class="docutils literal notranslate"><span class="pre">qemu-system-x86_64</span></code> executable when starting the emulation.</p></li>
<li><p><strong>metadata</strong> - Once the test job becomes part of an automated submission or
a <abbr title="Continuous Integration">CI</abbr> <a class="reference internal" href="glossary.html#term-ci-loop"><span class="xref std std-term">loop</span></a>, metadata needs
to be used to identify each submission, provide information on exactly what
changed from the last test job and information on how other users can modify
the test job artifacts to extend or debug the results.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="standard-test-jobs.html#job-metadata"><span class="std std-ref">Metadata</span></a>, <a class="reference internal" href="lava_ci.html#continuous-integration"><span class="std std-ref">Continuous Integration</span></a> and
<a class="reference internal" href="custom-result-handling.html#ci-loop"><span class="std std-ref">Closing the CI loop</span></a></p>
</div>
</li>
</ul>
<p>General details of the test job are specified in the top level elements, such
as in this snippet from the first job:</p>
<pre class="code yaml literal-block"><code><span class="name tag">device_type</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">qemu</span><span class="whitespace">
</span><span class="name tag">job_name</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">QEMU pipeline, first job</span><span class="whitespace">

</span><span class="name tag">timeouts</span><span class="punctuation">:</span><span class="whitespace">
  </span><span class="name tag">job</span><span class="punctuation">:</span><span class="whitespace">
    </span><span class="name tag">minutes</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">15</span><span class="whitespace">
  </span><span class="name tag">action</span><span class="punctuation">:</span><span class="whitespace">
    </span><span class="name tag">minutes</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">5</span><span class="whitespace">
  </span><span class="name tag">connection</span><span class="punctuation">:</span><span class="whitespace">
    </span><span class="name tag">minutes</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">2</span><span class="whitespace">
</span><span class="name tag">priority</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">medium</span><span class="whitespace">
</span><span class="name tag">visibility</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">public</span></code></pre>
</section>
<section id="actions-within-the-test-job">
<h2>Actions within the test job<a class="headerlink" href="#actions-within-the-test-job" title="Permalink to this heading">¶</a></h2>
<p>Each test job needs a list of actions, comprising of <code class="docutils literal notranslate"><span class="pre">deploy</span></code>, <code class="docutils literal notranslate"><span class="pre">boot</span></code> and
<code class="docutils literal notranslate"><span class="pre">test</span></code>.</p>
<ul class="simple">
<li><p><strong>deploy</strong> - download files required to boot the device and prepare an
overlay of files to run in the test action.</p></li>
<li><p><strong>boot</strong> - specify the method to boot the device and the prompts which will
dictate whether the device is considered to have been booted correctly.</p></li>
<li><p><strong>test</strong> - specify the repositories to clone which will provide the scripts
which will run the test you want to execute for this job.</p></li>
</ul>
<section id="deploy-action-for-qemu">
<span id="first-deploy-action-qemu"></span><h3>Deploy action for QEMU<a class="headerlink" href="#deploy-action-for-qemu" title="Permalink to this heading">¶</a></h3>
<p>Deployment methods are identified by the <code class="docutils literal notranslate"><span class="pre">to</span></code> parameter, for QEMU the
supported deployment method is to <code class="docutils literal notranslate"><span class="pre">tmpfs</span></code>. The image to deploy is specified
as an image dictionary which supports the formatting of the options to QEMU and
the compression algorithm to use to decompress the download prior to passing to
QEMU.</p>
<p>Arguments to QEMU need to include the filename, often embedded within a
specific option string. To achieve this, LAVA supports a <code class="docutils literal notranslate"><span class="pre">label</span></code> for the
image which will be substituted into the option.</p>
<pre class="code yaml literal-block"><code><span class="punctuation indicator">-</span><span class="whitespace"> </span><span class="name tag">deploy</span><span class="punctuation">:</span><span class="whitespace">
    </span><span class="name tag">timeout</span><span class="punctuation">:</span><span class="whitespace">
      </span><span class="name tag">minutes</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">5</span><span class="whitespace">
    </span><span class="name tag">to</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">tmpfs</span><span class="whitespace">
    </span><span class="name tag">images</span><span class="punctuation">:</span><span class="whitespace">
      </span><span class="name tag">rootfs</span><span class="punctuation">:</span><span class="whitespace">
        </span><span class="name tag">image_arg</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">-drive format=raw,file={rootfs}</span><span class="whitespace">
        </span><span class="name tag">url</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">https://images.validation.linaro.org/kvm/standard/stretch-2.img.gz</span><span class="whitespace">
        </span><span class="name tag">compression</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">gz</span></code></pre>
<p>The other role of a deploy action is to prepare the overlay which will contain
the test shell scripts and repositories. These will be added to the booted
image and then executed automatically, generating the results for the test job.</p>
<p>Certain aspects of executing tests on a booted device require knowledge about
which <abbr title="operating system">OS</abbr> will be running after the device has
booted. This is particularly relevant when the test scripts may require
additional dependencies to be installed in the running system. The test scripts
need to know whether to use <code class="docutils literal notranslate"><span class="pre">apt</span></code> or <code class="docutils literal notranslate"><span class="pre">yum</span></code> or something else to do the
installation work. Some other OS deployments may change other elements within
the test, so the test job submission will <strong>fail</strong> if the <code class="docutils literal notranslate"><span class="pre">os</span></code> parameter is
not set or is set to an unrecognized string.</p>
<p>Supported operating systems include <code class="docutils literal notranslate"><span class="pre">debian</span></code>, <code class="docutils literal notranslate"><span class="pre">ubuntu</span></code>, <code class="docutils literal notranslate"><span class="pre">oe</span></code> (for
OpenEmbedded) and <code class="docutils literal notranslate"><span class="pre">fedora</span></code>.</p>
<section id="example-of-deploy-label-substitution">
<h4>Example of deploy label substitution<a class="headerlink" href="#example-of-deploy-label-substitution" title="Permalink to this heading">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">https://images.validation.linaro.org/kvm/standard/stretch-2.img.gz</span></code> is
downloaded and then decompressed using the <code class="docutils literal notranslate"><span class="pre">gz</span></code> algorithm to create a file
called <code class="docutils literal notranslate"><span class="pre">stretch-2.img</span></code> in a <code class="docutils literal notranslate"><span class="pre">tmpfs</span></code> location. This location is then
substituted into the <code class="docutils literal notranslate"><span class="pre">image_arg</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">drive</span> <span class="nb">format</span><span class="o">=</span><span class="n">raw</span><span class="p">,</span><span class="n">file</span><span class="o">=/</span><span class="n">tmp</span><span class="o">/</span><span class="n">tmp</span><span class="mf">.23</span><span class="n">FDsf</span><span class="o">/</span><span class="n">stretch</span><span class="o">-</span><span class="mf">2.</span><span class="n">img</span>
</pre></div>
</div>
</section>
</section>
<section id="boot-action-for-qemu">
<h3>Boot action for QEMU<a class="headerlink" href="#boot-action-for-qemu" title="Permalink to this heading">¶</a></h3>
<p>One of the primary roles of the boot action parameters is to ensure that the
correct pipeline is constructed for this test job. The specified method is used
to match against the available boot methods. In this case, the boot method is
to call QEMU. The <code class="docutils literal notranslate"><span class="pre">qemu</span></code> boot method also needs the <code class="docutils literal notranslate"><span class="pre">media</span></code> parameter set
to <code class="docutils literal notranslate"><span class="pre">tmpfs</span></code> to distinguish this from other boot methods. The first job uses a
<a class="reference internal" href="glossary.html#term-test-shell"><span class="xref std std-term">test shell</span></a> and needs to specify the list of <a class="reference internal" href="glossary.html#term-prompts"><span class="xref std std-term">prompts</span></a> which LAVA
can recognize to start the operation of the test shell.</p>
<pre class="code yaml literal-block"><code><span class="punctuation indicator">-</span><span class="whitespace"> </span><span class="name tag">boot</span><span class="punctuation">:</span><span class="whitespace">
    </span><span class="name tag">timeout</span><span class="punctuation">:</span><span class="whitespace">
      </span><span class="name tag">minutes</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">2</span><span class="whitespace">
    </span><span class="name tag">method</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">qemu</span><span class="whitespace">
    </span><span class="name tag">media</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">tmpfs</span><span class="whitespace">
    </span><span class="name tag">prompts</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="punctuation indicator">[</span><span class="literal string">&quot;root&#64;debian:&quot;</span><span class="punctuation indicator">]</span><span class="whitespace">
    </span><span class="name tag">auto_login</span><span class="punctuation">:</span><span class="whitespace">
      </span><span class="name tag">login_prompt</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal string">&quot;login:&quot;</span><span class="whitespace">
      </span><span class="name tag">username</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">root</span></code></pre>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><strong>prompts</strong> - it is <strong>essential</strong> that the test writer records the
information on what prompt will be presented when the system boots into that
image successfully. If LAVA fails to match device output to provided prompt
string the job will fail with timeout on auto_login_action.</p>
</div>
</section>
<section id="test-action-for-qemu">
<h3>Test action for QEMU<a class="headerlink" href="#test-action-for-qemu" title="Permalink to this heading">¶</a></h3>
<p>The test action block in the first job contains two sets of definition
parameters, each consisting of:</p>
<ul class="simple">
<li><p><strong>repository</strong> - the URL to pass to git to clone the repository</p></li>
<li><p><strong>from</strong> - the method of obtaining the repository.</p></li>
<li><p><strong>path</strong> - full path to the YAML file inside the repository which contains
the Lava Test Shell Definition to be used for this test.</p></li>
<li><p><strong>name</strong> - the name to use when executing this test.</p></li>
</ul>
<p>The test action block in the first job also includes a timeout as an example of
how to specify a timeout for a particular section of the job.</p>
<pre class="code yaml literal-block"><code><span class="punctuation indicator">-</span><span class="whitespace"> </span><span class="name tag">test</span><span class="punctuation">:</span><span class="whitespace">
    </span><span class="name tag">timeout</span><span class="punctuation">:</span><span class="whitespace">
      </span><span class="name tag">minutes</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">5</span><span class="whitespace">
    </span><span class="name tag">definitions</span><span class="punctuation">:</span><span class="whitespace">
    </span><span class="punctuation indicator">-</span><span class="whitespace"> </span><span class="name tag">repository</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">http://git.linaro.org/lava-team/lava-functional-tests.git</span><span class="whitespace">
      </span><span class="name tag">from</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">git</span><span class="whitespace">
      </span><span class="name tag">path</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">lava-test-shell/smoke-tests-basic.yaml</span><span class="whitespace">
      </span><span class="name tag">name</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">smoke-tests</span><span class="whitespace">
    </span><span class="punctuation indicator">-</span><span class="whitespace"> </span><span class="name tag">repository</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">https://git.linaro.org/lava-team/lava-functional-tests.git</span><span class="whitespace">
      </span><span class="name tag">from</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">git</span><span class="whitespace">
      </span><span class="name tag">path</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">lava-test-shell/single-node/singlenode03.yaml</span><span class="whitespace">
      </span><span class="name tag">name</span><span class="punctuation">:</span><span class="whitespace"> </span><span class="literal scalar plain">singlenode-advanced</span></code></pre>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p>Back to your first job <a class="reference internal" href="first-job.html#job-submission"><span class="std std-ref">Job Submission</span></a>.</p>
</div>
</section>
</section>
</section>


    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
        &copy; Copyright 2010-2019, Linaro Limited.<br/>
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
    </p>
  </div>
</footer>
  </body>
</html>